Celestin Apprentice 4/Apprentice-Release4.iso/Source Code/OpenDoc/ProcessMap/CPProcessMap.Doc.cpp

Text File | 1995-04-14 | 43.8 KB | 1,148 lines | [TEXT/MPCC]

//----------------------------------------------------------------------------------------
// CPProcessMap.Doc.cp - Documentation for ProcessMap methods.
//----------------------------------------------------------------------------------------

// PART
void Explain_Constructor();
void Explain_Destructor();
void Explain_InitPart();
void Explain_InitPartFromStorage();
void Explain_Externalize();
void Explain_Open();
void Explain_Release();
void Explain_ReleaseAll();
void Explain_IncrementRefCount();
void Explain_CloneInto();

// EXTENSIONS
void Explain_HasExtension();
void Explain_GetExtension();
void Explain_ReleaseExtension();

// DRAGDROP
void Explain_DragLeave();
void Explain_Drop();
void Explain_DragWithin();
void Explain_DragEnter();
void Explain_DropCompleted();
void Explain_FulfillPromise();

// EMBED
void Explain_ContainingPartPropertiesChanged();
void Explain_GetContainingPartProperties();
void Explain_RevealFrame();
void Explain_EmbeddedFrameSpec();
void Explain_CreateEmbeddedFramesIterator();
void Explain_EmbeddedFrameChanged();

// EVENTS
void Explain_HandleEvent();
void Explain_AdjustMenus();

// FOCUS
void Explain_BeginRelinquishFocus();
void Explain_CommitRelinquishFocus();
void Explain_AbortRelinquishFocus();
void Explain_FocusAcquired();
void Explain_FocusLost();

// FRAMES
void Explain_DisplayFrameAdded();
void Explain_DisplayFrameConnected();
void Explain_DisplayFrameRemoved();
void Explain_DisplayFrameClosed();
void Explain_FrameShapeChanged();
void Explain_AttachSourceFrame();
void Explain_ViewTypeChanged();
void Explain_PresentationChanged();
void Explain_SequenceChanged();
void Explain_WritePartInfo();
void Explain_ReadPartInfo();
void Explain_RequestEmbeddedFrame();
void Explain_RemoveEmbeddedFrame();
void Explain_RequestFrameShape();
void Explain_UsedShapeChanged();
void Explain_AdjustBorderShape();

// FACETS
void Explain_FacetAdded();
void Explain_FacetRemoved();
void Explain_CanvasChanged();
void Explain_GeometryChanged();

// IMAGING
void Explain_Draw();
void Explain_CanvasUpdated();
void Explain_HighlightChanged();
void Explain_GetPrintResolution();

// LINKING
void Explain_CreateLink();
void Explain_LinkUpdated();
void Explain_RevealLink();
void Explain_LinkStatusChanged();

// UNDO
void Explain_UndoAction();
void Explain_RedoAction();
void Explain_DisposeActionState();
void Explain_WriteActionState();
void Explain_ReadActionState();

// BINDING
void Explain_ExternalizeKinds();
void Explain_ChangeKind();

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// PART
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_Constructor() {}

//----------------------------------------------------------------------------------------

void Explain_Destructor() {}

//----------------------------------------------------------------------------------------

void Explain_InitPart() {}

//----------------------------------------------------------------------------------------

void Explain_InitPartFromStorage() {}

//----------------------------------------------------------------------------------------

void Explain_Externalize() {}

//----------------------------------------------------------------------------------------

void Explain_Open() {}

// Creates and opens a presentation of the part in a frame
// in a new window.
//
// This method adds this part as the root part of the window.
// It bases the presentation in the new frame on the presentation
// in the old frame, or on a default presentation if there
// is no old frame.

//----------------------------------------------------------------------------------------

void Explain_Release() {}

// If you are using RegisterIdle on the part, not on frames, then
// the RefCount is bumped up by one by OpenDoc.  OpenDoc keeps a
// reference to all parts that register idle time.  ALL OF THESE MUST
// BE RESOLVED BEFORE THE DESTRUCTOR IS CALLED.  This is
// the place to do that.

// The logic below, assuming that CPProcessMap has registered for idle
// time, is that if the RefCount is 1, then we are here to unregister
// the idle.  When the part is being removed, OpenDoc must decrement
// the RefCount and call Release until the part gets messaged with
// a RefCount of 0.  Once you return from here with a RefCount of 0,
// OpenDoc will call the destructor.

// This means that if you have registered for idle time, Release will
// be called TWICE when closing down your part.  The first time the
// RefCount is 1.  This is when you should unregister the idle time.
// When you are called with a RefCount of 0, that when it gets really
// serious.  This is when you detach from the draft.

//----------------------------------------------------------------------------------------

void Explain_ReleaseAll() {}

//----------------------------------------------------------------------------------------

void Explain_IncrementRefCount() {}

//----------------------------------------------------------------------------------------

void Explain_CloneInto() {}

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// EXTENSIONS
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_HasExtension() {}

//----------------------------------------------------------------------------------------

void Explain_GetExtension() {}

//----------------------------------------------------------------------------------------

void Explain_ReleaseExtension() {}

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// IMAGING
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_Draw() {}

// Draws the part in the facet, updating the portion of the
// facet in the invalidShape.
//
// Called by the facet object.
//
// The part should draw itself on the facet's canvas. The part
// must examine its canvas' isDynamic flag to determine if it
// will be drawing on the screen or to a printer, and then draw
// itself appropriately.
//
// Draw the part in the given facet. Only the portion in the
// invalidShape needs to be drawn.
//
// There are several steps a part needs to take to perform the
// imaging.
// 1) The part should look at the given facet and its frame.
//    Both the frame and the facet may have some partInfo that
//    the part has placed there, which the part can use to
//    decide how it will display itself.  The frame also has
//    viewType and presentation fields, which indicate what kind
//    of view of the part should display.
// 2) The part should examine its canvas to see how it should
//    be imaged. The canvas can be obtained from the facet via
//    ODFacet::GetCanvas(). If the canvas’ isDynamic flag is
//    kODTrue, the part is imaging onto a dynamic device like
//    a CRT; otherwise, it is imaging to a static device like
//    a printer. The part will probably display its content
//    differently for static and dynamic views. For instance,
//    it should not display scroll bars on a static canvas.
// 3) The part must make sure the platform graphics system is
//    prepared to draw into the correct context for the facet.
//    On the Macintosh using QuickDraw, it is necessary to call
//    SetPort() for the appropriate canvas, and set up other
//    attributes of the drawing environment. A FocusLib library
//    is supplied to help focus drawing commands to a facet.
//    Make sure to clip to the facet’s clipShape (FocusLib
//    does this for you).
// 4) Draw the part’s contents.
// 5) Restore the old graphics environment.
//
// Part editors may sometimes need to display their parts
// asynchronously, that is, not in response to a ::Draw() call.
// This process is very similar to the basic drawing recipe,
// with minor modifications.
// 1) Determine which of the part’s frames should be drawn. A part
//    may have multiple display frames, and more than one may need
//    updating. Parts store their display frames in whatever way
//    they want, so we can’t tell you how to find them here.
// 2) For each frame being displayed, all facets must be drawn.
//    ODFrame::CreateFrameFacetIterator() returns an iterator
//    which will list all the facets of a frame. Draw the part’s
//    contents in each of these facets, using the recipe above.
// 3) After drawing in a facet, call ODFacet::DrawnIn() on it to
//    tell it you’ve drawn in it asynchronously. If the facet is
//    on an offscreen canvas, this lets it get copied into the window.

//----------------------------------------------------------------------------------------

void Explain_CanvasUpdated() {}

// Notifies the part that a canvas that it owns has been
// updated and that its contents need to be copied to its
// parent canvas.
//
// Called by the facet object.
//
// The data must be copied from an off-screen canvas,
// transformed, and then placed in the containing canvas.

//----------------------------------------------------------------------------------------

void Explain_HighlightChanged() {}

// Notifies the part that the highlight state of one of its
// frames has been changed.
//
// Called by the frame object.
//
// It adjusts this part's presentation in the facet to its
// new highlight state. New state may be found by calling
// facet->GetHighlight(). It passes notification to embedded
// parts.

//----------------------------------------------------------------------------------------

void Explain_GetPrintResolution() {}

// Returns the minimum desired resolution in dots per inch
// that this part requires for printing the contents of the
// specified frame.
//
// Called by part or the application and is used in performing
// printing.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// DRAG AND DROP
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_DragLeave() {}

// Signals that the drag operation is complete, and so
// deactivates the part from drag tracking.
//
// This method un-highlights any content previously highlighted
// during drag tracking. It also removes the drag target border.
// Before calling this method you must ensure that the part was
// previously activated via DragEnter().  After executing this
// method successfully, the part is no longer active, and cannot
// receive further DragWithin() or Drop() messages.
//
// DragLeave() is called when the mouse leaves a droppable frame.
// This allows the part to clean up after a drag within it
// (e.g., removing adornment on the frame, changing the cursor
// back to its original form).

//----------------------------------------------------------------------------------------

void Explain_Drop() {}

// Transfers the dragged data into this part.
//
// Called by the facet object.
//
// Respond to the Drop operation. This might involve moving or
// copying data in to the part, or some other response entirely.
// However, the response should use the data returned from the
// dropInfo iterator to perform the operation. Before calling
// this method, you must ensure that the part was previously
// activated via DragEnter().
//
// Don't forget whether the drop is a move or a copy.
//
// Drop() is called when the mouse is released within a part which
// owns the facet. The part can then figure out whether it can
// receive the dragged object using the ODDragItemIterator passed
// in. The following is a sample code fragment for incorporating
// text into a part.
//
// The destination part should return an appropriate ODDropResult
// from Drop(). This result tells the source part (via the system)
// whether the drop is accepted.

//----------------------------------------------------------------------------------------

void Explain_DragWithin() {}

// Tracks the drag operation, and provides graphical feedback
// regarding possible drop targets.
//
// This method highlights the appropriate content to provide
// feedback about potential drop targets, based on type of dragged
// data. It gets the type information out of the dragInfo. During
// drag tracking (DragEnter, DragWithin) the part should never
// attempt to read data from any of the storage units supplied by
// the iterator. The part should only inspect the type of the
// dragged data. Before calling tis method, you must ensure that
// the part was previously activated via DragEnter().
//
// DragWithin() is called continuously when the mouse is still in
// the facet. This allows the part to do any processing desired.
// One good example is when the frame has several hot spots where
// objects can be dropped. If the mouse is not over these hot spots,
// the cursor may need to be changed to reflect that the no
// dropping can be done there even though it is still in a
// droppable frame. Again, a ODDragItemIterator is passed in so
// that the part can examine the availabe data types of the dragged
// objects.
//
// DragWithin() also provides a chance for the part to examine the
// state of the machine. For example, some part may want to find
// out whether the modifier keys are down or not.

//----------------------------------------------------------------------------------------

void Explain_DragEnter() {}

// Activates the part used to track the drag.
//
// Called by the facet object.
//
// The part should display a drag target border within the facet.
// During drag tracking (DragEnter, DragWithin) the part should
// never attempt to read data from any of the storage units supplied
// by the iterator. The part should only inspect the type of the
// dragged data. Before calling this method, you must ensure that
// the part is ready to receive DrawWithin messages.
//
// DragEnter() is called when the mouse enters a facet.  The part
// should examine the available data types of the dragged items
// using the ODDragItemIterator passed in.  If the part can handle
// a drop of the dragged object, it should provide the appropriate
// feedback (e.g., adorning the droppable frame, changing the cursor).
// If the destination part cannot handle the data types, nothing
// should be done.

//----------------------------------------------------------------------------------------

void Explain_DropCompleted() {}

// Notifies the part that the drop is completed.
//
// Called by the dragAndDrop object.
//
// DropCompleted is a peculiar method. If DragAndDrop::StartDrag is
// synchronous, the return code to DragAndDrop::StartDrag is the
// drop result. Part::DropCompleted does not need to be called.
// However, if it is required that DragAndDrop::StartDrag returns
// immediately, there needs to be a way to notify the result of the
// drop. Before calling this method, you must ensure that the part
// previously started an asynchronous drag.

//----------------------------------------------------------------------------------------

void Explain_FulfillPromise() {}

// Fulfills a previously made promise by providing the actual
// data the promise represents.
//
// The promiseSUView is a view into the same storage unit value
// that is created by SetPromiseValue. The information about the
// promise is encoded in the promiseSUView in the Part Handler's
// own internal format. The promise data is written into the
// promiseSUView replacing the data stored in the part handler's
// format.
//
// When the promise was made, a record of it was kept by this part.
// The promiseSUView contains the part's information for that promise.
// The part uses the data in the promiseSUView to determine which
// data to move/copy. The part then writes the data into the
// promiseSUView.
//
// The format of a promise is determined by the part. The only
// restriction is that a promise must be able to be written to
// a Storage Unit Value.
//
// The destination part does not even know that the fulfilment
// of a promise is taking place.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// EMBEDDING
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_ContainingPartPropertiesChanged() {}

// Used by ContainingPart to inform the contained part of
// changes to the content properties of that object within
// the containing part’s content model that encapsulates the
// embedded frame.
//
// This method inspects “propertyUnit” for properties that this
// part can understand. Where applicable, it incorporate those
// properties into part's content data. It ignores inapplicable
// properties, without signalling an error.

//----------------------------------------------------------------------------------------

void Explain_GetContainingPartProperties() {}

// Used by an embedded part to create a storage unit and write
// properties that the containing part associates with the
// embedded frame into it, before returning it.
//
// Called by an embedded part.

//----------------------------------------------------------------------------------------

void Explain_RevealFrame() {}

// Asks a part to make an embedded frame visible.
//
// Called by an embedded part.
//
// This method scrolls one of this part's display frame's to make
// the embedded frame visible therein. If this part has no visible
// frames, it asks a containing part to reveal one of them. If no
// display frames for the part currently exist, or if this part's
// containing frame can't reveal the display frame, it opens a frame
// in a new window.

//----------------------------------------------------------------------------------------

void Explain_EmbeddedFrameSpec() {}

// Creates an object specifier for the embedded frame.
//
// If this part is itself embedded, this method asks its containing
// part for the specifier for the part's display frame, then
// concatenates the specifier for that embedded frame.

//----------------------------------------------------------------------------------------

void Explain_CreateEmbeddedFramesIterator() {}

// Creates an object that will iterate over the frames that
// are embedded within a display frame of this part.
//
// To indicate all the display frames, use kODNull for the frame
// parameter.

//----------------------------------------------------------------------------------------

void Explain_EmbeddedFrameChanged() {}

// Notifies the containing part that the content displayed
// in the argument “embedded frame” has changed.
//
// Called by an frame object belonging to an embedded part when
// the frame object's ContentChanged method is called.
//
// The part should call the ContentChanged method of any of its
// frames that would be interested in this information. This
// method should only be called by frame objects. The part is
// not responsible for passing this notification on to its
// containing part. The part may ignore this notification if it
// is uninterested in changes to embedded content. A part should
// wait a certain length of time (a second perhaps) before
// updating its display so that subsequent calls to
// EmbeddedFrameChanged with the same ODChangeID don’t result
// in multiple updates for the same change.After executing this
// method successfully, the ContentChanged method of any of the
// part's frames may have been called and the part may have
// taken action to update its display.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// EVENTS
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_HandleEvent() {}

// Below is some documentation for this method.  If you don't care for
// being here, then just delete it.
//
// The frame and facet parameters of HandleEvent() may be
// kODNULL, depending on the kind of event.
//
// Parts must handle the following events, which correspond to
// standard Macintosh events:
//
//    kODEvtNull
//     kODEvtMouseDown
//     kODEvtMouseUp
//     kODEvtKeyDown
//     kODEvtKeyUp
//     kODEvtAutoKey
//     kODEvtUpdate
//     kODEvtActivate
//     kODEvtOS
//
// Null Events --
// In order to receive null events (i.e. idle time), parts must call
// ODDispatcher::RegisterIdle(), specifying the part, a frame
// (optional) and idle frequency. The part will receive a null event
// for each frame registered. ODDispatcher::GetSleepTime() is called
// by the shell, and the value passed to WaitNextEvent. An appropriate
// sleep time is computed based on the idle frequencies of registered
// idle frames.
//
// Mouse Events --
// Unmodified mouse events are delivered to the facet under the mouse
// location using Part::HandleEvent().
//
// Shift-Click and Command-Click go to the frame with the selection
// focus.  Mouse events in window title bars are converted to window
// events. (See below)  Mouse down events in the menu bar are converted
// to menu events. (See below)
//
// Keyboard Events --
// Keyboard events go to the frame with the keyboard focus, with the
// exception of the Page Up, Page Down, Home and End keys, which will
// go to the frame with the scrolling focus, if there is one.
//
// Update Events --
// Update events are not passed to Part::HandleEvent(). Rather
// Part::Draw() will be called for each facet in the window.
//
// Activate Events --
// Activate events are also delivered to each facet, using
// Part::HandleEvent().
//
// Disk Events --
// Currently, disk events are not distributed to parts.
// But where do they go???
//
// OS Events --
// Suspend/Resume events are delivered to each facet in each
// window using Part::HandleEvent().
//
// Mouse Moved events are not passed to Part::HandleEvent().
// They are handled by the dispatcher, and translated into calls
// to Part::MouseEnter(), MouseWithin() and MouseLeave().
// See Cursor Tracking below.
//
// Menu Events --
// OpenDoc converts a mouse down in the menu bar, or its
// command-key equivalent, into a menu event of type kODEvtMenu.
//
// The message field of the event record contains the result
// returned by MenuSelect() or MenuKey(). i.e. the menu is in
// the high word, and the item in the low word. The part can
// obtain a command number using ODMenuBar::GetCommand().
//
// Window Events --
// Events in the title bar of a window (eg. clicking in the
// close box) are usually handled by the shell, but are first
// offered to the root part of the window. Parts which wish to
// intercept these events (perhaps to hide rather than close a
// window) must handle the following event: kODEvtWindow
// The message field of the event contains the part code, as
// returned by FindWindow().
//
// Events in Embedded Frames --
// Parts which support embedding may also receive the following events:
//
//    kODEvtMouseDownEmbedded
//    kODEvtMouseUpEmbedded
//    kODEvtMouseDownBorder
//    kODEvtMouseUpBorder
//
// If the user clicks in the active border, the containing
// facet/frame/part will receive a kODEvtMouseDownBorder event.
// The message field of the event record contains the embedded facet.
//
// Similarly, if the user clicks in an embedded frame with the
// “frozen” or “selected” property set, a kODEvtMouseDownEmbedded
// event is directed to the containing frame.
//
// If the user shift-clicks or command-clicks in a frame which is
// embedded in the frame with the selection focus, then the latter
// frame gets a kODEvtMouseDownEmbedded event.
//
// Cursor Tracking --
// OpenDoc tracks cursor movement (with the mouse button up), and
// calls MouseEnter() when the cursor first moves into a facet, and
// MouseLeave() when the cursor leaves the facet. A part can change
// the cursor on MouseEnter, and set it to the arrow on MouseLeave.
//
// This process is triggered by the shell calling
// ODDispatcher::GetMouseRegion() and passing the result to
// WaitNextEvent(). The region is only recomputed when necessary.
// If the cursor is motionless within a facet, the shell application
// goes to sleep because OpenDoc computes a mouse region containing
// just the cursor location. The part can make this region larger
// by calling ODDispatcher::SetMouseRegion(). In a future release,
// OpenDoc will also compute a suitably large sleep region if the
// cursor is not within any facet.
//
// Modal Focus --
// Some events are constrained by the modal focus. For example a
// mouse click outside the frame with the modal focus will be sent
// to the modal focus frame, but a click in an embedded frame
// within the modal focus frame will go to the embedded frame.
//
// Propagating Events --
// If a containing part sets the “DoesPropagateEvents” property of
// an embedded frame, the containing part will receive events not
// handled by the embedded frame. A part which does this will have
// to inspect the frame passed to HandleEvent() to determine if it
// is one of its display frames.

//----------------------------------------------------------------------------------------

void Explain_AdjustMenus() {}

// WRITE YOUR OWN

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// FOCUSING
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_BeginRelinquishFocus() {}

//----------------------------------------------------------------------------------------

void Explain_CommitRelinquishFocus() {}

// No choices to be made here.  It's too late to say no.  We are
// losing the focus if we are here.  Getting called here means
// that BeginRelinquishFocus has already agreed that losing focus
// is okay.  If you don't want this to be happening, then you need
// to do something in BeginRelinquishFocus.
//
// The way that some other samples are currently written I believe
// to be in error.  The recipes say that when this is called, it
// has already been decided that, focus-wise, you lose.  Therefore
// there should be no conditions on calling FocusLost.

//----------------------------------------------------------------------------------------

void Explain_AbortRelinquishFocus() {}

// Being here means that BeginRelinquishFocus said no to one of the foci.
// You are being informed of this because you may have already taken action
// based on a previous focus.  Note that if foci are managed as a set, if
// BeginRelinquishFocus says false to any of the foci, then no action is
// taken.  If however the foci are tested one at a time, it is possible that
// the part has already taken action based on the first foci, and therefore
// needs to undo something once a foci says no thanks.

//----------------------------------------------------------------------------------------

void Explain_FocusAcquired() {}

// WRITE YOUR OWN

//----------------------------------------------------------------------------------------

void Explain_FocusLost() {}

// WRITE YOUR OWN

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// FRAME
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_DisplayFrameAdded() {}

// Tells a part to add “frame” as one of its display frames.
//
// This method is only called by frame objects during their
// initialization.  Same for RemoveDisplayFrame() and
// CloseDisplayFrame().
//
// The part must record “frame” in whatever internal structures it
// uses to remember its display frames. The new frame will carry a
// suggested viewType and presentation information. The part should
// look at those settings, and decide if it can support them; if not,
// it should update those settings in the frame to reflect a default
// presentation that it can support. Note that the part must support
// the required set of standard viewTypes (frame, icon, small icon,
// thumbnail, etc.). The part will then create the appropriate
// partInfo data and store it in the frame. This data allows the part
// to distinguish the frame from its other display frames, and is
// also a handy place to store other view-related information.
//
// Add the new display frame to the part’s list of its display frames.
// This list, like the part’s other internal structures, is completely
// hidden from OpenDoc. The developer may represent this list any way
// he chooses. The simplest of parts may be able to do without such a
// list, but most parts will require it.
//
// Validate the viewType and presentation of the new frame. The part
// must support the required set of view types. Other kinds of view
// types or presentations are optional. The part should inspect these
// values and correct them if necessary. See the recipe for View Types
// and Presentations for more detail.
//
// Add partInfo to the frame. The partInfo field of a frame is a
// convenient place for a part to store information about that view of
// itself. It can be anything from a simple ID to a pointer to a
// complicated structure or a helper object. The partInfo for a frame
// is stored in the storage unit for the frame, not the part. If the
// part has many frames of which only a few are internalized, only the
// partInfo of those frames will be internalized and take up memory.
//
// The display frames need not be internalized until needed and will be
// done by the containing part. ???

//----------------------------------------------------------------------------------------

void Explain_DisplayFrameConnected() {}

//----------------------------------------------------------------------------------------

void Explain_DisplayFrameRemoved() {}

// Will remove the frame from the list of display frames.
//
// Called by Frame::Remove().
//
// This method makes whatever other adjustments are necessary
// to deal with removing one of the presentations. This includes
// removing any frames embedded within this display frame.
// Before calling this method, you must ensure that the frame
// has no facets.

//----------------------------------------------------------------------------------------

void Explain_DisplayFrameClosed() {}


// Informs a part that one of its display frames is closing.
//
// Called by the frame object.
// The part should remove “frame” from its list of display frames,
// call Frame::Close() on any frames that are embedded within that
// frame, and then release the frame.

//----------------------------------------------------------------------------------------

void Explain_FrameShapeChanged() {}


// Notifies the part that the frame shape of one of its
// display frames has been changed by its containing part.
//
// Called by Frame::ChangeFrameShape.
//
// The part should take whatever actions are necessary to respond
// to the new shape. It may need to re-layout its content, change
// its used shape, resize its embedded frames, or something else.
// It also has the option of turning around and asking the frame
// for a different frame shape via RequestFrameShape, though it
// must be able to handle the shape it is given. If the size of
// the frame is not sufficient, the part may ask the containing
// part for a continuation frame via CreateEmbeddedFrame.

//----------------------------------------------------------------------------------------

void Explain_AttachSourceFrame() {}

// Called by the object that requested creation of a frame,
// immediately after the creation of the frame.
//
// Calling this method associates a “source frame” with a display
// frame of a part. This tells the part to keep two or more of its
// display frames synchronized.
//
// A part will receive this call just after a display frame has
// been added. Attaching a source frame should cause the display
// frame to look identical to it. If presentations differ, it
// causes the display frame to be equivalent to it. This causes
// duplication of the embedded frames, and ensures that the view
// in one frame is updated when content in the other is changed.
// Before calling this method, you must ensure that both frame
// and sourceFrame are display frames of the part.
//
// The part being displayed should take whatever action necessary
// to synchronize the frames. As a minimum, if the two frames are
// the same kind of presentation, it should duplicate embedded
// frames in one frame into the other.

//----------------------------------------------------------------------------------------

void Explain_ViewTypeChanged() {}

// Notifies the part that the viewType of one of its
// frames has been changed.
//
// Parts must support all standard view types.
// And they are ... ???

//----------------------------------------------------------------------------------------

void Explain_PresentationChanged() {}

// Notifies the part that the presentation kind of one
// of its frames has been changed.
//
// Called by Frame::ChangeViewType().
//
// The part should examine the new view type via
// frame->GetViewType(). If the part does not support that kind
// of view type, it should correct the frame's viewType using
// frame->SetViewType(). Note that parts MUST support the
// standard set of view types (se HI spec). The part should then
// adjust its display in the display frame to be of the new view
// type.

//----------------------------------------------------------------------------------------

void Explain_SequenceChanged() {}

// Informs the part that the sequencing of a group of its
// display frames has been changed.
//
// Called by containing part.
//
// The containing part of frame should call this when adding a new
// frame to the group or re-ordering the frames in the group. A
// single frame of the group is passed as an argument to indicate
// which group of which containing frame has been changed.

//----------------------------------------------------------------------------------------

void Explain_WritePartInfo() {}

// Externalizes the frame's partInfo data onto the frame's
// storage unit.
//
// Called by the frame object.
//
// Duh???

//----------------------------------------------------------------------------------------

void Explain_ReadPartInfo() {}

// Internalizes the partInfo for a display frame of this part.
//
//
// Called by the frame object.
//
// The data for the partInfo is stored in a value in the frame's
// storage unit, specified by the suView parameter. It gets the
// data from out of the value, and places it in a block of memory.
// It then returns the memory block to the frame for it to hold.

//----------------------------------------------------------------------------------------

void Explain_RequestEmbeddedFrame() {}

// Asks the part to create a new frame and embed a part in it.
//
// This is only requested by embedded parts which want additional
// frames in which to display in the same containing part.
//
// If this part is a containing part, it should ask the draft to
// create a new frame, and embed the frame in its content.
// “baseFrame” is another display frame of the same part, already
// embedded in the same containing part. The frameShape parameter
// is relative to the frame coordinate system of the baseFrame.
// The containing part decides if it can fulfill the requests for
// frameShape. - if not, it can create the frame where it wants
// and with the shape it chooses. The containing part should assign
// the new frame to the same frameGroup as the baseFrame. If
// isOverlaid is true, the new frame should float above the part's
// content, and should not have to negotiate for space with the part.
// The viewType and presentation are just passed through to
// Draft::CreateFrame().
//
// Note that RequestEmbeddedFrame should only be called by an embedded
// part on its containing part in order to get a sibling frame.  That
// is why this call takes a baseFrame parameter.  The baseFrame must
// already be embedded inside the part receiving the
// RequestEmbeddedFrame message.

//----------------------------------------------------------------------------------------

void Explain_RemoveEmbeddedFrame() {}

// Removes a frame used for viewing an embedded part.
//
// Called by an embedded part.
//
// It is called by an embedded part to indicate it no longer
// needs the frame to display itself.

//----------------------------------------------------------------------------------------

void Explain_RequestFrameShape() {}

// Used by an embedded part to ask for a change in the
// shape of its frame.
//
// Called by Frame::RequestFrameShape().
//
// This method decides what new shape to give the embedded frame,
// using the requested “frameShape” as a guideline. It then
// answers with what shape is actually granted as the return value.
// The requestor must abide by the returned shape, though it may
// make further requests for different shapes or additional frames.

//----------------------------------------------------------------------------------------

void Explain_UsedShapeChanged() {}

// Informs a containing part that the used shape of one of
// its embedded frames has changed.
//
// Called by Frame::ChangeUsedShape().
//
// Containing parts that have arranged their content to conform
// to the used shape of an embedded frame (as in text wrapping)
// will need to adjust the layout of that content for the new
// used shape.

//----------------------------------------------------------------------------------------

void Explain_AdjustBorderShape() {}

// Adjusts the shape of the active frame border of an embedded
// frame.
//
// Called by the arbitrator object.
//
// The “shape” parameter specifies the requested shape. The
// return value specifies that shape as it is obscured by the
// other contents of this part.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_FacetAdded() {}

//----------------------------------------------------------------------------------------

void Explain_FacetRemoved() {}

//----------------------------------------------------------------------------------------

void Explain_CanvasChanged() {}

// Notifies the part that one of its facets has been moved to
// image on a different canvas.
//
// Called by the facet object.
//
// The part must update any internal state necessary for
// compliance with this method.

//----------------------------------------------------------------------------------------

void Explain_GeometryChanged() {}

// Called by a facet of the part to inform it that the clipping
// shape and/or external transform of that facet has changed.
//
// Called by the facet object.
//
// The part should use the new clip shape for display from now
// on. Parts that display only in response to update events don't
// need to do anything special, provided they check the clip
// shape each time they draw. Parts that display asynchronously
// (like clocks, movies, etc.) must notice their new clipping and
// limit their display accordingly.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// LINKING
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_CreateLink() {}

// Creates a new link object.
//
// If a link already exists to the content identified by the data
// and size arguments, this method returns the link object;
// otherwise, it creates a new link object, puts in the initial
// data and returns it to the caller.
//
// This method identifies the content to be linked (by resolving
// the object specifier saved in the data parameter, or by some
// other means). It then creates a link object to represent the
// content data. The part must maintain information about what
// portion of its contents have been linked to it, so that it may
// notify link clients when that data has been changed. The link
// created is returned to the caller. Before calling this method,
// you must ensure that the data identifies some portion of this
// part's contents. After calling this method successfully, this
// part maintains a link to the identified content.

//----------------------------------------------------------------------------------------

void Explain_LinkUpdated() {}

// Retrieves the data from the link and incorporates it into
// this part at the link's destination, thereby replacing any
// previous content of the link.

//----------------------------------------------------------------------------------------

void Explain_RevealLink() {}


// Reveals data that was previously linked in a window, making it
// available for viewing in a display frame.
//
// Called by ODLinkSource objects.  Should not be called by parts.
// In some display frame for this part, this method selects the
// content linked by the linkSource argument, and scrolls it into
// view. That display frame is made the active frame. If no display
// frames for the part currently exist, or if this part's containing
// frame can't reveal the display frame, it opens a frame in a new
// window.

//----------------------------------------------------------------------------------------

void Explain_LinkStatusChanged() {}

// Allows the part to set the link status of any embedded frames.
//
// Called by a part's frame when that frame's ChangeLinkStatus
// method is called.
//
// Frames notify their owner parts that their link status has
// changed whenever ChangeLinkStatus is called. After this
// method executes successfully, the part will call
// ChangeLinkStatus on any embedded frames that are involved
// in the link in question.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// UNDO
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_UndoAction() {}

// Tells the part to undo the action that is described by actionState.
//
// Called by the undo object.

//----------------------------------------------------------------------------------------

void Explain_RedoAction() {}

// Tells the part to Redo the action described by actionState.
//
// Called by the undo object.

//----------------------------------------------------------------------------------------

void Explain_DisposeActionState() {}

// Tells the part to dispose of the action data.
//
// Before calling this method, you must ensure that “actionState”
// is an action data block previously logged by this part. After
// calling this method successfully, memory for “actionState” has
// been reclaimed. It is no longer usable to perform undo operations.

//----------------------------------------------------------------------------------------

void Explain_WriteActionState() {}

// Writes out the actionState data onto a StorageUnitView,
// and externalizes the undoAction data to the storage unit.
//
// Called by the undo object.

//----------------------------------------------------------------------------------------

void Explain_ReadActionState() {}

// Internalizes the undoAction data from the storage unit.
//
// This method reads the actionState data from a view on a
// StorageUnit. It then allocates the memory and passes ownership
// of the storage to the caller.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••
// BINDING
//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

void Explain_ExternalizeKinds() {}

// Externalizes a representation for each 'kind' that it supports.
//
// The part should iterate through all the kinds in 'kindList',
// and externalize a representation for each that it supports.
// This call does not specify anything about the ordering of those
// kinds in the contents property. Before calling this method,
// you must ensure that the part supports a subset of the kinds
// in 'kindList'. After executing this method successfully, the
// contents property of the part has a value and representation
// for each kind in kindListsupported.

//----------------------------------------------------------------------------------------

void Explain_ChangeKind() {}

// Asks a part to change into a new kind of content,
// i.e. ask an ASCII Text part to change into a Styled Text part.
//
// The part should begin using the given kind as its primary kind
// if it is supported. The first type of the first value in the
// content property of the part's storage unit should become the
// given kind. Before calling this method, you must ensure that the
// part supports the specified kind. After this method is executed
// successfully, the part's primary kind is the one that was
// specified in the parameter, and the first type of the first
// value in the content property of the part's storage unit is of
// the specified type. When it reads in data, the part uses this
// representation.

//••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••